
<!DOCTYPE html>
<!--

    Copyright (c) 2017, 2019 Oracle and/or its affiliates. All rights reserved.

    This program and the accompanying materials are made available under the
    terms of the Eclipse Public License v. 2.0, which is available at
    http://www.eclipse.org/legal/epl-2.0.

    This Source Code may also be made available under the following Secondary
    Licenses when the conditions for such availability set forth in the
    Eclipse Public License v. 2.0 are satisfied: GNU General Public License,
    version 2 with the GNU Classpath Exception, which is available at
    https://www.gnu.org/software/classpath/license.html.

    SPDX-License-Identifier: EPL-2.0 OR GPL-2.0 WITH Classpath-exception-2.0

-->
<!-- Portions Copyright [2019] [Payara Foundation and/or its affiliates] -->
<html lang="en">
  <head>
    <meta charset="utf-8"/>
    <title>create-instance</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <link href="css/style.css" rel="stylesheet">
    <script src="https://use.fontawesome.com/96c4d89611.js"></script>
  </head>
  <body>
<table id="doc-title" cellspacing="0" cellpadding="0">
  <tr>
  <td align="left" valign="top">
  <b>create-instance</b><br />
  </td>
  </tr>
</table>
<hr />

<table width="90%" id="top-nav" cellspacing="0" cellpadding="0">
	<colgroup>
		<col width="12%"/>
		<col width="12%"/>
		<col width="*"/>
	</colgroup>
	<tr>
		<td align="left">
		<a href="create-iiop-listener.html">
			<span class="vector-font"><i class="fa fa-arrow-circle-left" aria-hidden="true"></i></span>
			<span style="position:relative;top:-2px;">Previous</span>
		</a>
		</td>

		<td align="left">
		<a href="create-jacc-provider.html">
			<span class=" vector-font"><i class="fa fa-arrow-circle-right vector-font" aria-hidden="true"></i></span>
			<span style="position:relative;top:-2px;">Next</span>
		</a>
		</td>

		<td align="right">
		<a href="toc.html">
			<span class=" vector-font"><i class="fa fa-list vector-font" aria-hidden="true"></i></span>
			<span style="position:relative;top:-2px;">Contents</span>
		</a>
		</td>
	</tr>
</table>


<div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p><a id="create-instance-1"></a><a id="GSRFM00033"></a><a id="create-instance"></a></p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_create_instance">create-instance</h2>
<div class="sectionbody">
<div class="paragraph">
<p>creates a \{product---name} instance</p>
</div>
<div id="sthref293" class="paragraph">
<p>Synopsis</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-oac_no_warn" data-lang="oac_no_warn">asadmin [asadmin-options] create-instance [--help]
--node node-name
[--config config-name | --cluster cluster-name]
[--lbenabled={true|false}]
[--portbase=port-number] [--checkports={true|false}]
[--systemproperties (name=value)[:name=value]* ]
instance-name</code></pre>
</div>
</div>
<div id="sthref294" class="paragraph">
<p>Description</p>
</div>
<div class="paragraph">
<p>The <code>create-instance</code> subcommand creates a \{product---name} instance.
This subcommand requires the Distributed Component Object Model (DCOM)
remote protocol or secure shell (SSH) to be configured on the host where
the domain administration server (DAS) is running and on the host that
is represented by the node where the instance is to reside.</p>
</div>
<div class="admonitionblock note">
<table>
<tr>
<td class="icon">
<div class="title">Note</div>
</td>
<td class="content">
<div class="paragraph">
<p>DCOM or SSH is not required if the instance is to reside on a node of
type <code>CONFIG</code> that represents the local host. A node of type <code>CONFIG</code> is
not enabled for remote communication over DCOM or SSH.</p>
</div>
</td>
</tr>
</table>
</div>
<div class="paragraph">
<p>You may run this command from any host that can contact the DAS.</p>
</div>
<div class="paragraph">
<p>A \{product---name} instance is a single Virtual Machine for the Java
platform (Java Virtual Machine or JVM machine) on a single node in which
\{product---name} is running. A node defines the host where the
\{product---name} instance resides. The JVM machine must be compatible
with the Java Platform, Enterprise Edition (Java EE).</p>
</div>
<div class="paragraph">
<p>A \{product---name} instance requires a reference to the following
items:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>The node that defines the host where the instance resides. The node
must be specified in the command to create the instance.</p>
</li>
<li>
<p>The named configuration that defines the configuration of the
instance. The configuration can be specified in the command to create
the instance, but is not required. If no configuration is specified for
an instance that is not joining a cluster, the subcommand creates a
configuration for the instance. An instance that is joining a cluster
receives its configuration from its parent cluster.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Each \{product---name} instance is one of the following types of
instance:</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">Standalone instance</dt>
<dd>
<p>A standalone instance does not share its configuration with any other
instances or clusters. A standalone instance is created if either of
the following conditions is met:<br></p>
<div class="ulist">
<ul>
<li>
<p>No configuration or cluster is specified in the command to create
the instance.</p>
</li>
<li>
<p>A configuration that is not referenced by any other instances or
clusters is specified in the command to create the instance.<br>
When no configuration or cluster is specified, a copy of the
<code>default-config</code> configuration is created for the instance. The name
of this configuration is instance-name`-config`, where instance-name
represents the name of an unclustered server instance.</p>
</li>
</ul>
</div>
</dd>
<dt class="hdlist1">Shared instance</dt>
<dd>
<p>A shared instance shares its configuration with other instances or
clusters. A shared instance is created if a configuration that is
referenced by other instances or clusters is specified in the command
to create the instance.</p>
</dd>
<dt class="hdlist1">Clustered instance</dt>
<dd>
<p>A clustered instance inherits its configuration from the cluster to
which the instance belongs and shares its configuration with other
instances in the cluster. A clustered instance is created if a cluster
is specified in the command to create the instance.<br>
Any instance that is not part of a cluster is considered an
unclustered server instance. Therefore, standalone instances and
shared instances are unclustered server instances.</p>
</dd>
</dl>
</div>
<div class="paragraph">
<p>By default, this subcommand attempts to resolve possible port conflicts
for the instance that is being created. The subcommand also assigns
ports that are currently not in use and not already assigned to other
instances on the same node. The subcommand assigns these ports on the
basis of an algorithm that is internal to the subcommand. Use the
<code>--systemproperties</code> option to resolve port conflicts for additional
instances on the same node. System properties of an instance can be
manipulated by using the
<a href="create-system-properties.html#create-system-properties-1"><code>create-system-properties</code>(1)</a>
subcommand and the
<a href="delete-system-property.html#delete-system-property-1"><code>delete-system-property</code>(1)</a>
subcommand.</p>
</div>
<div class="paragraph">
<p>This subcommand is supported in remote mode only.</p>
</div>
<div id="sthref295" class="paragraph">
<p>Options</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">asadmin-options</dt>
<dd>
<p>Options for the <code>asadmin</code> utility. For information about these
options, see the <a href="asadmin.html#asadmin-1m"><code>asadmin</code>(1M)</a> help page.</p>
</dd>
<dt class="hdlist1"><code>--help</code></dt>
<dt class="hdlist1"><code>-?</code></dt>
<dd>
<p>Displays the help text for the subcommand.</p>
</dd>
<dt class="hdlist1"><code>--node</code></dt>
<dd>
<p>The name of the node that defines the host where the instance is to be
created. The node must already exist. If the instance is to be created
on the host where the domain administration server (DAS) is running,
use the predefined node `localhost-`domain.</p>
</dd>
<dt class="hdlist1"><code>--config</code></dt>
<dd>
<p>Specifies the named configuration that the instance references. The
configuration must exist and must not be named <code>default-config</code> or
<code>server-config</code>. Specifying the <code>--config</code> option creates a shared
instance.<br>
The <code>--config</code> option and the <code>--cluster</code> option are mutually
exclusive. If both options are omitted, a standalone instance is
created.</p>
</dd>
<dt class="hdlist1"><code>--cluster</code></dt>
<dd>
<p>Specifies the cluster from which the instance inherits its
configuration. Specifying the <code>--cluster</code> option creates a clustered
instance.<br>
The <code>--config</code> option and the <code>--cluster</code> option are mutually
exclusive. If both options are omitted, a standalone instance is
created.</p>
</dd>
<dt class="hdlist1"><code>--lbenabled</code></dt>
<dd>
<p>Specifies whether the instance is enabled for load balancing. Possible
values are as follows:<br></p>
<div class="dlist">
<dl>
<dt class="hdlist1"><code>true</code></dt>
<dd>
<p>The instance is enabled for load balancing (default).<br>
When an instance is enabled for load balancing, a load balancer
sends requests to the instance.</p>
</dd>
<dt class="hdlist1"><code>false</code></dt>
<dd>
<p>The instance is disabled for load balancing.<br>
When an instance is disabled for load balancing, a load balancer
does not send requests to the instance.</p>
</dd>
</dl>
</div>
</dd>
<dt class="hdlist1"><code>--portbase</code></dt>
<dd>
<p>Determines the number with which the port assignment should start. An
instance uses a certain number of ports that are statically assigned.
The portbase value determines where the assignment should start. The
values for the ports are calculated as follows:<br></p>
<div class="ulist">
<ul>
<li>
<p>Administration port: portbase + 48</p>
</li>
<li>
<p>HTTP listener port: portbase + 80</p>
</li>
<li>
<p>HTTPS listener port: portbase + 81</p>
</li>
<li>
<p>JMS port: portbase + 76</p>
</li>
<li>
<p>IIOP listener port: portbase + 37</p>
</li>
<li>
<p>Secure IIOP listener port: portbase + 38</p>
</li>
<li>
<p>Secure IIOP with mutual authentication port: portbase + 39</p>
</li>
<li>
<p>JMX port: portbase + 86</p>
</li>
<li>
<p>JPA debugger port: portbase + 9</p>
</li>
<li>
<p>Felix shell service port for OSGi module management: portbase + 66<br>
When the <code>--portbase</code> option is specified, the output of this
subcommand includes a complete list of used ports.</p>
</li>
</ul>
</div>
</dd>
<dt class="hdlist1"><code>--checkports</code></dt>
<dd>
<p>Specifies whether to check for the availability of the administration,
HTTP, JMS, JMX, and IIOP ports. The default value is <code>true</code>.</p>
</dd>
<dt class="hdlist1"><code>--systemproperties</code></dt>
<dd>
<p>Defines system properties for the instance. These properties override
property definitions for port settings in the instance&#8217;s
configuration. Predefined port settings must be overridden if, for
example, two clustered instances reside on the same host. In this
situation, port settings for one instance must be overridden because
both instances share the same configuration.<br>
The following properties are available:<br></p>
<div class="dlist">
<dl>
<dt class="hdlist1"><code>ASADMIN_LISTENER_PORT</code></dt>
<dd>
<p>This property specifies the port number of the HTTP port or HTTPS
port through which the DAS connects to the instance to manage the
instance. Valid values are 1-65535. On UNIX, creating sockets that
listen on ports 1-1024 requires superuser privileges.</p>
</dd>
<dt class="hdlist1"><code>HTTP_LISTENER_PORT</code></dt>
<dd>
<p>This property specifies the port number of the port that is used to
listen for HTTP requests. Valid values are 1-65535. On UNIX,
creating sockets that listen on ports 1-1024 requires superuser
privileges.</p>
</dd>
<dt class="hdlist1"><code>HTTP_SSL_LISTENER_PORT</code></dt>
<dd>
<p>This property specifies the port number of the port that is used to
listen for HTTPS requests. Valid values are 1-65535. On UNIX,
creating sockets that listen on ports 1-1024 requires superuser
privileges.</p>
</dd>
<dt class="hdlist1"><code>IIOP_LISTENER_PORT</code></dt>
<dd>
<p>This property specifies the port number of the port that is used for
IIOP connections. Valid values are 1-65535. On UNIX, creating
sockets that listen on ports 1-1024 requires superuser privileges.</p>
</dd>
<dt class="hdlist1"><code>IIOP_SSL_LISTENER_PORT</code></dt>
<dd>
<p>This property specifies the port number of the port that is used for
secure IIOP connections. Valid values are 1-65535. On UNIX, creating
sockets that listen on ports 1-1024 requires superuser privileges.</p>
</dd>
<dt class="hdlist1"><code>IIOP_SSL_MUTUALAUTH_PORT</code></dt>
<dd>
<p>This property specifies the port number of the port that is used for
secure IIOP connections with client authentication. Valid values are
1-65535. On UNIX, creating sockets that listen on ports 1-1024
requires superuser privileges.</p>
</dd>
<dt class="hdlist1"><code>JAVA_DEBUGGER_PORT</code></dt>
<dd>
<p>This property specifies the port number of the port that is used for
connections to the Java Platform Debugger Architecture (JPDA)
debugger. Valid values are 1-65535. On UNIX, creating sockets that
listen on ports 1-1024 requires superuser privileges.</p>
</dd>
<dt class="hdlist1"><code>JMS_PROVIDER_PORT</code></dt>
<dd>
<p>This property specifies the port number for the Java Message Service
provider. Valid values are 1-65535. On UNIX, creating sockets that
listen on ports 1-1024 requires superuser privileges.</p>
</dd>
<dt class="hdlist1"><code>JMX_SYSTEM_CONNECTOR_PORT</code></dt>
<dd>
<p>This property specifies the port number on which the JMX connector
listens. Valid values are 1-65535. On UNIX, creating sockets that
listen on ports 1-1024 requires superuser privileges.</p>
</dd>
<dt class="hdlist1"><code>OSGI_SHELL_TELNET_PORT</code></dt>
<dd>
<p>This property specifies the port number of the port that is used for
connections to the Apache Felix Remote Shell
(<code>http://felix.apache.org/site/apache-felix-remote-shell.html</code>).
This shell uses the Felix shell service to interact with the OSGi
module management subsystem. Valid values are 1-65535. On UNIX,
creating sockets that listen on ports 1-1024 requires superuser
privileges.</p>
</dd>
</dl>
</div>
</dd>
</dl>
</div>
<div id="sthref296" class="paragraph">
<p>Operands</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">instance-name</dt>
<dd>
<p>The name of the instance that is being created.<br>
The name must meet the following requirements:<br></p>
<div class="ulist">
<ul>
<li>
<p>The name may contain only ASCII characters.</p>
</li>
<li>
<p>The name must start with a letter, a number, or an underscore.</p>
</li>
<li>
<p>The name may contain only the following characters:</p>
<div class="ulist">
<ul>
<li>
<p>Lowercase letters</p>
</li>
<li>
<p>Uppercase letters</p>
</li>
<li>
<p>Numbers</p>
</li>
<li>
<p>Hyphen</p>
</li>
<li>
<p>Period</p>
</li>
<li>
<p>Underscore</p>
</li>
</ul>
</div>
</li>
<li>
<p>The name must be unique in the domain and must not be the name of
another \{product---name} instance, a cluster, a named configuration,
or a node.</p>
</li>
<li>
<p>The name must not be <code>domain</code>, <code>server</code>, or any other keyword that
is reserved by \{product---name}.</p>
</li>
</ul>
</div>
</dd>
</dl>
</div>
<div id="sthref297" class="paragraph">
<p>Examples</p>
</div>
<div class="paragraph">
<p><a id="GSRFM487"></a><a id="sthref298"></a></p>
</div>
<div class="paragraph">
<p>Example 1   Creating a Standalone \{product---name} Instance</p>
</div>
<div class="paragraph">
<p>This example creates the standalone \{product---name} instance
<code>pmdsainst</code> in the domain <code>domain1</code> on the local host.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-oac_no_warn" data-lang="oac_no_warn">asadmin&gt; create-instance --node localhost-domain1 pmdsainst
Port Assignments for server instance pmdsainst:
JMX_SYSTEM_CONNECTOR_PORT=28688
JMS_PROVIDER_PORT=27678
ASADMIN_LISTENER_PORT=24850
HTTP_LISTENER_PORT=28082
IIOP_LISTENER_PORT=23702
IIOP_SSL_LISTENER_PORT=23822
HTTP_SSL_LISTENER_PORT=28183
IIOP_SSL_MUTUALAUTH_PORT=23922

Command create-instance executed successfully.</code></pre>
</div>
</div>
<div class="paragraph">
<p><a id="GSRFM488"></a><a id="sthref299"></a></p>
</div>
<div class="paragraph">
<p>Example 2   Creating a Standalone \{product---name} Instance With Custom
Port Assignments</p>
</div>
<div class="paragraph">
<p>This example creates the standalone \{product---name} instance
<code>pmdcpinst</code> in the domain <code>domain1</code> on the local host. Custom port
numbers are assigned to the following ports:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>HTTP listener port</p>
</li>
<li>
<p>HTTPS listener port</p>
</li>
<li>
<p>IIOP connections port</p>
</li>
<li>
<p>Secure IIOP connections port</p>
</li>
<li>
<p>Secure IIOP connections port with mutual authentication</p>
</li>
<li>
<p>JMX connector port</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-oac_no_warn" data-lang="oac_no_warn">asadmin&gt; create-instance --node localhost-domain1
--systemproperties HTTP_LISTENER_PORT=58294:
HTTP_SSL_LISTENER_PORT=58297:
IIOP_LISTENER_PORT=58300:
IIOP_SSL_LISTENER_PORT=58303:
IIOP_SSL_MUTUALAUTH_PORT=58306:
JMX_SYSTEM_CONNECTOR_PORT=58309 pmdcpinst
Port Assignments for server instance pmdcpinst:
JMS_PROVIDER_PORT=27679
ASADMIN_LISTENER_PORT=24851

Command create-instance executed successfully.</code></pre>
</div>
</div>
<div class="paragraph">
<p><a id="GSRFM489"></a><a id="sthref300"></a></p>
</div>
<div class="paragraph">
<p>Example 3   Creating a Shared \{product---name} Instance</p>
</div>
<div class="paragraph">
<p>This example creates the shared \{product---name} instance
<code>pmdsharedinst1</code> in the domain <code>domain1</code> on the local host. The shared
configuration of this instance is <code>pmdsharedconfig</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-oac_no_warn" data-lang="oac_no_warn">asadmin create-instance --node localhost-domain1 --config pmdsharedconfig
pmdsharedinst1
Port Assignments for server instance pmdsharedinst1:
JMX_SYSTEM_CONNECTOR_PORT=28687
JMS_PROVIDER_PORT=27677
ASADMIN_LISTENER_PORT=24849
HTTP_LISTENER_PORT=28081
IIOP_LISTENER_PORT=23701
IIOP_SSL_LISTENER_PORT=23821
HTTP_SSL_LISTENER_PORT=28182
IIOP_SSL_MUTUALAUTH_PORT=23921

Command create-instance executed successfully.</code></pre>
</div>
</div>
<div class="paragraph">
<p><a id="GSRFM490"></a><a id="sthref301"></a></p>
</div>
<div class="paragraph">
<p>Example 4   Creating a Clustered \{product---name} Instance</p>
</div>
<div class="paragraph">
<p>This example creates the clustered \{product---name} instance <code>pmdinst1</code>
in the domain <code>domain1</code> on the local host. The instance is a member of
the cluster <code>pmdclust1</code>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="prettyprint highlight"><code class="language-oac_no_warn" data-lang="oac_no_warn">asadmin&gt; create-instance --node localhost-domain1 --cluster pmdclust pmdinst1
Port Assignments for server instance pmdinst1:
JMX_SYSTEM_CONNECTOR_PORT=28686
JMS_PROVIDER_PORT=27676
HTTP_LISTENER_PORT=28080
ASADMIN_LISTENER_PORT=24848
IIOP_SSL_LISTENER_PORT=23820
IIOP_LISTENER_PORT=23700
HTTP_SSL_LISTENER_PORT=28181
IIOP_SSL_MUTUALAUTH_PORT=23920

Command create-instance executed successfully.</code></pre>
</div>
</div>
<div id="sthref302" class="paragraph">
<p>Exit Status</p>
</div>
<div class="dlist">
<dl>
<dt class="hdlist1">0</dt>
<dd>
<p>command executed successfully</p>
</dd>
<dt class="hdlist1">1</dt>
<dd>
<p>error in executing the command</p>
</dd>
</dl>
</div>
<div id="sthref303" class="paragraph">
<p>See Also</p>
</div>
<div class="paragraph">
<p><a href="asadmin.html#asadmin-1m"><code>asadmin</code>(1M)</a></p>
</div>
<div class="paragraph">
<p><a href="create-local-instance.html#create-local-instance-1"><code>create-local-instance</code>(1)</a>,
<a href="create-node-config.html#create-node-config-1"><code>create-node-config</code>(1)</a>,
<a href="create-node-dcom.html#create-node-dcom-1"><code>create-node-dcom</code>(1)</a>,
<a href="create-node-ssh.html#create-node-ssh-1"><code>create-node-ssh</code>(1)</a>,
<a href="create-system-properties.html#create-system-properties-1"><code>create-system-properties</code>(1)</a>,
<a href="delete-instance.html#delete-instance-1"><code>delete-instance</code>(1)</a>,
<a href="delete-system-property.html#delete-system-property-1"><code>delete-system-property</code>(1)</a>,
<a href="list-instances.html#list-instances-1"><code>list-instances</code>(1)</a>,
<a href="setup-ssh.html#setup-ssh-1"><code>setup-ssh</code>(1)</a>,
<a href="start-instance.html#start-instance-1"><code>start-instance</code>(1)</a>,
<a href="stop-instance.html#stop-instance-1"><code>stop-instance</code>(1)</a></p>
</div>
</div>
</div>

<hr />

<table width="90%" id="bottom-nav" cellspacing="0" cellpadding="0">
	<colgroup>
		<col width="12%"/>
		<col width="12%"/>
		<col width="*"/>
	</colgroup>
	<tr>		
		<td align="left">
		<a href="create-iiop-listener.html">
			<span class=" vector-font"><i class="fa fa-arrow-circle-left" aria-hidden="true"></i></span>
			<span style="position:relative;top:-2px;">Previous</span>
		</a>
		</td>

		<td align="left">
		<a href="create-jacc-provider.html">
			<span class="vector-font"><i class="fa fa-arrow-circle-right vector-font" aria-hidden="true"></i></span>
			<span style="position:relative;top:-2px;">Next</span>
		</a>
		</td>

		<td align="right">
		<a href="toc.html">
			<span class="vector-font"><i class="fa fa-list vector-font" aria-hidden="true"></i></span>
			<span style="position:relative;top:-2px;">Contents</span>
		</a>
		</td>
	</tr>
</table>

<span id="copyright">
        <img src="/resource/reference/img/eclipse_foundation_logo_tiny.png" height="20px" alt="Eclipse Foundation Logo" align="top"/>&nbsp;            
        <span >Copyright&nbsp;&copy;&nbsp;2019,&nbsp;Oracle&nbsp;and/or&nbsp;its&nbsp;affiliates.&nbsp;All&nbsp;rights&nbsp;reserved.</span>
</span>

</body>
</html>
